package com.carbeauty.service;

import com.carbeauty.entity.User;
import com.carbeauty.common.enums.UserRole;
import com.carbeauty.common.enums.BusinessStatus;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.util.List;
import java.util.Optional;

/**
 * 用户服务接口
 * 
 * 提供用户管理的业务逻辑:
 * - 用户基础CRUD操作
 * - 用户认证和授权
 * - 密码管理
 * - 用户状态管理
 * - 用户统计分析
 * 
 * @author CarBeauty Team
 */
public interface UserService {
    
    // ==================== 基础CRUD操作 ====================
    
    /**
     * 保存用户信息
     * 
     * @param user 用户信息
     * @return 保存后的用户信息
     */
    User save(User user);
    
    /**
     * 根据ID查找用户
     * 
     * @param id 用户ID
     * @return 用户信息
     */
    Optional<User> findById(Long id);
    
    /**
     * 根据ID获取用户（如果不存在抛出异常）
     * 
     * @param id 用户ID
     * @return 用户信息
     * @throws RuntimeException 用户不存在时抛出异常
     */
    User getById(Long id);
    
    /**
     * 删除用户（逻辑删除）
     * 
     * @param id 用户ID
     */
    void deleteById(Long id);
    
    /**
     * 批量删除用户
     * 
     * @param ids 用户ID列表
     */
    void deleteByIds(List<Long> ids);
    
    // ==================== 查询操作 ====================
    
    /**
     * 查找所有活跃用户
     * 
     * @return 活跃用户列表
     */
    List<User> findAllActive();
    
    /**
     * 分页查询活跃用户
     * 
     * @param pageable 分页参数
     * @return 用户分页数据
     */
    Page<User> findAllActive(Pageable pageable);
    
    /**
     * 根据用户名查找用户
     * 
     * @param username 用户名
     * @return 用户信息
     */
    Optional<User> findByUsername(String username);
    
    /**
     * 根据手机号查找用户
     * 
     * @param phone 手机号
     * @return 用户信息
     */
    Optional<User> findByPhone(String phone);
    
    /**
     * 根据邮箱查找用户
     * 
     * @param email 邮箱
     * @return 用户信息
     */
    Optional<User> findByEmail(String email);
    
    /**
     * 根据角色查找用户
     * 
     * @param role 用户角色
     * @return 用户列表
     */
    List<User> findByRole(UserRole role);
    
    /**
     * 多条件搜索用户
     * 
     * @param username 用户名（模糊匹配）
     * @param realName 真实姓名（模糊匹配）
     * @param phone 手机号（模糊匹配）
     * @param role 用户角色
     * @param status 用户状态
     * @return 符合条件的用户列表
     */
    List<User> searchUsers(String username, String realName, String phone, UserRole role, BusinessStatus status);
    
    // ==================== 认证相关 ====================
    
    /**
     * 用户登录验证
     * 
     * @param username 用户名
     * @param password 密码
     * @return 登录成功的用户信息
     */
    User login(String username, String password);
    
    /**
     * 更新用户登录信息
     * 
     * @param userId 用户ID
     * @param loginIp 登录IP
     */
    void updateLoginInfo(Long userId, String loginIp);
    
    /**
     * 修改密码
     * 
     * @param userId 用户ID
     * @param oldPassword 旧密码
     * @param newPassword 新密码
     * @return 是否修改成功
     */
    boolean changePassword(Long userId, String oldPassword, String newPassword);
    
    /**
     * 重置密码
     * 
     * @param userId 用户ID
     * @param newPassword 新密码
     */
    void resetPassword(Long userId, String newPassword);
    
    // ==================== 用户状态管理 ====================
    
    /**
     * 启用用户
     * 
     * @param userId 用户ID
     */
    void enableUser(Long userId);
    
    /**
     * 禁用用户
     * 
     * @param userId 用户ID
     */
    void disableUser(Long userId);
    
    /**
     * 检查用户是否活跃
     * 
     * @param userId 用户ID
     * @return 是否活跃
     */
    boolean isUserActive(Long userId);
    
    // ==================== 数据验证 ====================
    
    /**
     * 验证用户名是否已存在
     * 
     * @param username 用户名
     * @param excludeId 排除的用户ID（用于更新时验证）
     * @return 是否存在
     */
    boolean isUsernameExists(String username, Long excludeId);
    
    /**
     * 验证手机号是否已存在
     * 
     * @param phone 手机号
     * @param excludeId 排除的用户ID
     * @return 是否存在
     */
    boolean isPhoneExists(String phone, Long excludeId);
    
    /**
     * 验证邮箱是否已存在
     * 
     * @param email 邮箱
     * @param excludeId 排除的用户ID
     * @return 是否存在
     */
    boolean isEmailExists(String email, Long excludeId);
    
    // ==================== 统计分析 ====================
    
    /**
     * 获取用户总数统计
     * 
     * @return 用户总数
     */
    long getTotalUserCount();
    
    /**
     * 获取今日新增用户数量
     * 
     * @return 今日新增用户数量
     */
    long getTodayNewUserCount();
    
    /**
     * 获取本月新增用户数量
     * 
     * @return 本月新增用户数量
     */
    long getThisMonthNewUserCount();
    
    /**
     * 获取各角色用户数量统计
     * 
     * @return 角色用户数量统计
     */
    List<Object[]> getUserRoleStatistics();
    
    /**
     * 获取在线用户数量
     * 
     * @return 在线用户数量
     */
    long getOnlineUserCount();
    
    /**
     * 查找长时间未登录的用户
     * 
     * @param days 天数
     * @return 未登录用户列表
     */
    List<User> findInactiveUsers(int days);
}
